---
title: "@assistant-ui/react-ai-sdk"
---

Vercel AI SDK integration for assistant-ui.

import { ParametersTable } from "@/components/docs";
import { Callout } from "fumadocs-ui/components/callout";

<Callout type="info">
  This package provides integration with AI SDK v5. For AI SDK v4, see the [AI
  SDK v4 (Legacy)](/docs/runtimes/ai-sdk/v4-legacy) documentation.
</Callout>

## API Reference

### `useChatRuntime`

Creates a runtime directly with AI SDK v5's `useChat` hook integration. This is the recommended approach for most use cases.

```tsx
import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/react-ai-sdk";
import { AssistantRuntimeProvider } from "@assistant-ui/react";

const MyRuntimeProvider = ({ children }: { children: React.ReactNode }) => {
  const runtime = useChatRuntime({
    transport: new AssistantChatTransport({
      api: "/api/chat",
    }),
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  );
};
```

To customize the API endpoint, simply change the `api` parameter:

```tsx
const runtime = useChatRuntime({
  transport: new AssistantChatTransport({
    api: "/my-custom-api/chat",
  }),
});
```

<ParametersTable
  parameters={[
    {
      name: "options",
      type: "UseChatRuntimeOptions",
      description: "Configuration options for the chat runtime.",
      children: [
        {
          type: "UseChatRuntimeOptions",
          parameters: [
            {
              name: "api",
              type: "string",
              description: "The API endpoint URL. Defaults to '/api/chat'.",
            },
            {
              name: "transport",
              type: "ChatTransport",
              description:
                "Custom transport implementation. Defaults to AssistantChatTransport which forwards system messages and tools.",
            },
            {
              name: "cloud",
              type: "AssistantCloud",
              description:
                "Optional AssistantCloud instance for chat persistence.",
            },
            {
              name: "initialMessages",
              type: "UIMessage[]",
              description: "Initial messages to populate the chat.",
            },
            {
              name: "onFinish",
              type: "(message: UIMessage) => void",
              description: "Callback when a message completes streaming.",
            },
            {
              name: "onError",
              type: "(error: Error) => void",
              description: "Callback for handling errors.",
            },
          ],
        },
      ],
    },
  ]}
/>

<Callout type="info">
  By default, `useChatRuntime` uses `AssistantChatTransport` which automatically
  forwards system messages and frontend tools to your backend API. This enables
  your backend to receive the full context from the assistant-ui.
</Callout>

### `useAISDKRuntime`

For advanced use cases where you need direct access to the `useChat` hook from AI SDK.

```tsx
import { useChat } from "@ai-sdk/react";
import { useAISDKRuntime } from "@assistant-ui/react-ai-sdk";
import { AssistantRuntimeProvider } from "@assistant-ui/react";

const MyRuntimeProvider = ({ children }: { children: React.ReactNode }) => {
  const chat = useChat({
    api: "/api/chat",
  });

  const runtime = useAISDKRuntime(chat);

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  );
};
```

<ParametersTable
  parameters={[
    {
      name: "chat",
      type: "ReturnType<typeof useChat>",
      description: "The chat helpers from @ai-sdk/react's useChat hook.",
    },
    {
      name: "options",
      type: "AISDKRuntimeOptions",
      description: "Optional configuration options.",
      children: [
        {
          type: "AISDKRuntimeOptions",
          parameters: [
            {
              name: "cloud",
              type: "AssistantCloud",
              description:
                "Optional AssistantCloud instance for chat persistence.",
            },
            {
              name: "adapters",
              type: "RuntimeAdapters",
              description:
                "Optional runtime adapters for attachments, feedback, speech, etc.",
            },
          ],
        },
      ],
    },
  ]}
/>

### `AssistantChatTransport`

A transport that extends the default AI SDK transport to automatically forward system messages and frontend tools to your backend.

```tsx
import { AssistantChatTransport } from "@assistant-ui/react-ai-sdk";
import { useChatRuntime } from "@assistant-ui/react-ai-sdk";

const runtime = useChatRuntime({
  transport: new AssistantChatTransport({
    api: "/my-custom-api/chat",
  }),
});
```

<ParametersTable
  parameters={[
    {
      name: "options",
      type: "HttpChatTransportInitOptions",
      description: "Transport configuration options.",
      children: [
        {
          type: "HttpChatTransportInitOptions",
          parameters: [
            {
              name: "api",
              type: "string",
              description: "The API endpoint URL.",
            },
            {
              name: "headers",
              type: "Record<string, string> | Headers",
              description: "Optional headers to include in requests.",
            },
            {
              name: "credentials",
              type: "RequestCredentials",
              description: "Optional credentials mode for fetch requests.",
            },
          ],
        },
      ],
    },
  ]}
/>

### `frontendTools`

Helper function to convert frontend tool definitions to AI SDK format for use in your backend.

```tsx
import { frontendTools } from "@assistant-ui/react-ai-sdk";
import { streamText, convertToModelMessages } from "ai";
import { openai } from "@ai-sdk/openai";

export async function POST(req: Request) {
  const { messages, system, tools } = await req.json();

  const result = streamText({
    model: openai("gpt-4o"),
    system,
    messages: convertToModelMessages(messages),
    tools: {
      // Wrap frontend tools with the helper
      ...frontendTools(tools),
      // Your backend tools
      myBackendTool: tool({
        // ...
      }),
    },
  });

  return result.toUIMessageStreamResponse();
}
```

<ParametersTable
  parameters={[
    {
      name: "tools",
      type: "Record<string, unknown>",
      description:
        "Frontend tools object forwarded from AssistantChatTransport.",
    },
  ]}
/>

<Callout type="info">
  The `frontendTools` helper converts frontend tool definitions to the AI SDK
  format and ensures they are properly handled by the streaming response.
</Callout>
